perm filename HEUTIL.WRU[SYS,HE]1 blob
sn#004175 filedate 1972-06-05 generic text, type T, neo UTF8
00100 THE HAND/EYE UTILITY ROUTINES
00200
00300 This file, containing the utility routines for the Hand/Eye
00400 system, can be obtained by REQUIRE "HEUTIL.SAI[SYS,HE]" SOURCE_FILE.
00500 This file REQUIREs the preamble and Quam's display package (version
00600 on LIB,HE). See IIDRV.WRU[SYS,HE] for the descriptin of an
00700 interpreter for running the routines from console input. Most
00800 internal variables are prefixed with 'U_' so there will be no
00900 conflicts with your symbols, unless you are in the habit of using the
01000 same prefix. The following variables and definitions may be of some
01100 use to you, but you are urged not to change the variables:
01200
01300 ⊃ is defined as COMMENT
01400 U_C is defined as carriage return and line feed
01500 U_BLOB is the set of all blob items. A blob is defined as a set of
01600 connected edges traced by the edge follower. It may be one or
01700 more objects.
01800 U_OBJ is the set of all object items. An object is something which
01900 was recognized by SIMPLE or COMPLEX.
02000
02100 DSEND,DWAIT, DKILL, DSOURCE, DDEST, DNAME, DWAITM, DACT, and DACK are
02200 control bits for message procedures as described in the
02300 message procedure documentation.
02400
02500
02600
02700
02800 INTERNAL PROCEDURES
02900
03000 The following procedures are mainly for internal use but may
03100 be of use to users:
03200
03300 1. STRING PROCEDURE PN(ITEMVAR X);
03400
03500 Returns the print name of the argument if it exists; the
03600 decimal item item number otherwise.
03700
03800 2. PROCEDURE U_RJEC(INTEGER ITEMVAR A);
03900
04000 Removes the item from the internal data structures. You
04100 should call this procedure before deleting a blob or object item if
04200 you did not call REJ_OBJ.
00100 UTILITY ROUTINES
00200
00300 Below are the utility procedures currently coded. Hopefully
00400 their appearance to the user will not change even when the internal
00500 workings do.
00600
00700 PROCEDURE U_INIT;
00800
00900 Initializes the utility routines and the program. It must be
01000 called before any other routines. Among other things, it generates
01100 local print names for all declared global items, initializes the page
01200 printer (no other hand/eye job should do this when running under the
01300 monitor) and passes its name, II, to the message procedure handler.
01400 If the type flag (TYP_II) is TRUE, this procedure, as well as several
01500 others will type out messages to let the user know they ran and what
01600 they did, or did not, do.
01700
01800 PROCEDURE TAB_SET;
01900
02000 Initializes the TABLE array in the global model which gives a
02100 3-D description of the world. Until TAB_SET is called, routines
02200 which update TABLE will not do so and routine which look at it should
02300 not.
02400
02500 INTEGER PROCEDURE JOB_START(STRING JOB);
02600
02700 Trys to make sure the specified job is logged in and running.
02800 JOB is the logical name of the job (see the section on job
02900 description and status for the logical names of currently implemented
03000 jobs. If the name is not recognized, the procedure returns -1.
03100 Otherwise, if the job specified is not running, it sends a message to
03200 the monitor to execute the proper login and load macro with the save
03300 PPN as the monitor. The macro file HEMACR[SYS,HE] must have been
03400 read in by the monitor. When the job is running 1 is returned. If
03500 the job did not start within the required time, a zero is returned
03600 and the job is probably not there. If you are running without the
03700 monitor, you will get a nasty message and the routine will not
03800 continue until you start the job. Note that this program decides if
03900 a job is running by checking its 'YES' flag in the global segment.
04000 It cannot tell if the job dies after setting its flag.
04100 Currently, the other utility procedures do not check if the
04200 jobs they are calling are there so you must (or at least should) call
04300 this routine before the first call of each job driver. With the
04400 description of each procedure are the logical names of the jobs which
04500 must be running for proper operation.
04600
04700 SET PROCEDURE GETEDGE(INTEGER COUNT);
04800
04900 JOBS: EDG (also CAM if SIMPLE or COMPLEX are to be called)
05000
05100 is the edge follower driver. This routine finds the outline
05200 of blobs, sometimes with a few interior edges also. COUNT is the
05300 number of blobs to find or <0 to find all blobs in the field of view.
05400 Due to the way the edge follower works you may get more blobs than
05500 you requested, but you will never get fewer unless there were not
05600 enough visible. Once the outline is found, there are two ways
05700 analysis of the scene can continue. The outline can be sent to CURVE
05800 and SIMPLE if the blob appears simple enough, or the inside edges can
05900 be tracing and everything sent to GUNNAR ( the region finder) and
06000 COMPLEX. Also, if CURVE did not find a closed curve, as required by
06100 SIMPLE, finding more edges and refitting may still get an outline
06200 SIMPLE can use.
06300 The procedure will always put out the data structure required
06400 for the SIMPLE route. If you want the option of calling either,
06500 however, COUNT must be zero on entry. This will get you at least one
06600 blob. If you are only using SIMPLE, setting it FALSE will speed the
06700 program up somewhat and take a little less core. Once this is done,
06800 COMPLEX cannot be used on the blobs found unless they are rejected
06900 and retraced. Utility routine EDGFIN will get the rest of the edges
07000 for COMPLEX, which INNER gets them, if necessary, for SIMPLE.
07700 The value of the procedure is the set of blob items
07800 processed. This set must be saved if COMPLEX may be used as all blobs
07900 from a single trace must be processed together. Some of the blobs may
08000 have been returned before. Seeing them again in the set means more
08100 edges were found and if CURVE was called for it, you might want to
08200 fit it again. The program will try to find as many new blobs as you
08300 requested.
08400
08500 The blob items have integer datums which contain a status
08600 word decoded as follows: (look but do not touch)
08700
08800 BIT NAME DESCRIPTION
08900 1 an edge was lost during accomodation
09000 2 an edge hit another edge
09100 4 an edge was outside the field of view
09200 10 U_CLOSE a closed curve has been found
09300 20 U_EDGE the blob has been traced
09400 40 U_CURV the blob has been curve fit (by CURVE)
09500 100 U_REC the blob has been completely recognized by
09600 COMPLEX
09700 200 U_SIMP the blob has been recognized by SIMPLE
09800 400 U_GUNN the blob has been processed by GUNNAR
09900 1000 U_GUN the blob was traced by EDGFIN
10000 2000 U_FINE the blob has been processed by INNER
10100
10200 SET PROCEDURE CURVE(SET BLOBS);
10300
10400 JOBS: EDG, CUR
10500
10600 is the curve fitter driver. BLOBS is the set of blobs to be
10700 curve fit, or {EVERY} to fit all of them. EVERY is a declared global
10800 item. A blob already fit will not be fit again unless more edges have
10900 been found for it. Also, some blobs may be deleted during the
11000 fitting process if the curve fitter decides they are too small to fit
11100 (i.e. patches of noise). The value of the procedure is the set of
11200 all blobs processed. The others were either deleted or already fit.
11300 In the latter case they are still in U_BLOB.
11400
11500 SET PROCEDURE EDGFIN(SET BLOBS);
11600
11700 JOBS: EDG (CAM if COMPLEX is to be called)
11800
11900 If you called GETEDGE with FLAG=TRUE and now want to process
12000 the blobs with the region finder, you must first call this routine to
12100 find the rest of the edge of the blobs. It need not be called if you
12200 requested all blobs when you called GETEDGE. The argument is a set
12300 of blobs returned by a single call of GETEDGE. The value of the
12400 procedure is PHI if the argument was not correct; otherwise it is the
12500 set of blobs processed, of which the argument is a subset. If you
12600 want more edges for SIMPLE, this routine will do it but INNER is
12700 recommended. This routine may be called more than once for a given
12800 blob, but will probably not find more edges.
12900
13000 STRING PROCEDURE GUNNAR(SET BLOBS);
13100
13200 JOBS: GUN
13300
13400 is the driver for the region finder which prepares blobs for
13500 COMPLEX. BLOBS is the output from a single call of EDGFIN. If the
13600 set is incorrect, NULL is the value of the procedure. Otherwise, the
13700 value is the name of the file containing the data for COMPLEX. Save
13800 the name to give to COMPLEX. A set of blobs cannot be given to this
13900 routine more than once.
14000
14100 SET PROCEDURE SIMPL(SET BLOBS, OBJECTS; REFERENCE SET NO_REC);
14200
14300 JOBS: SIM
14400
14500 is the driver for SIMPLE. BLOBS is a set of blobs to be
14600 recognized. Unlike for the COMPLEX processing, they need not be from
14700 a single call of GETEDGE. OBJECTS is the set of prototypes you are
14800 interested in, such as CUBE, RPP122, etc. or {EVERY} if you don't
14900 care. The value of the procedure is the set of object items generated
15000 for recognized blobs. NO_REC contains the set of blobs rejected.
15100 Either they were not recognized or they were recognized as prototypes
15200 not found in OBJECTS. Blobs recognized previously or not yet curve
15300 fit and given to SIMPLE again are ignored and will not appear in
15400 either set. Once a blob is returned in the value set, it will not be
15500 sent to SIMPLE again, even if more edges are found.
15600
15700 [the global model output of SIMPLE will be defined later. For now it
15800 is described PREAMB.TXT[II,HE] ]
15802
15804 BOOLEAN PROCEDURE NEW_SIMP(REAL ARRAY ITEMVAR OBJ; REAL ARRAY TRANS);
15806
15808 Changes the world model when an object is moved. OBJ is the
15810 object item with the old transform. TRANS is the transfrom the
15812 object should have after the move. The result is FALSE only if OBJ
15814 has not already been processed by SIMPLE. The edge follower data
15816 structure will be updated and the display of the object, if any, is
15818 turned off. The object will not be displayed at its new location.
15900
16000 PROCEDURE COMP(SET OBJS);
16100
16200 JOBS: EDG
16300
16400 This routine calls the edge follower to compact its data
16500 structure. OBJS is a set of objects to be compacted. Each item must
16600 have an EDGES association in the global model. This procedure can be
16700 used to tell the edge follower about objects it did not trace, to
16800 define areas inside of which it is not to look, to redefine objects
16900 when the camera transform is changed, or to save space and speed up
17000 edge tracing. See the discussion of the COMPACT command in
17100 EYE.WRU[SYS,HE] for more information. After all objects created from
17200 a blob have been compacted, the blob and its data structure are
17300 deleted.
17400
17500 PROCEDURE REJ_OBJ(SET ITMS);
17600
17700 JOBS: EDG
17800
17900 All items in the set are deleted after all global
18000 associations generated by any of the other jobs are erased and the
18100 edge follower has been called to remove the item from its internal
18200 structures. After all objects associated with a blob have been
18300 deleted, the blob is deleted also.
18400
18500 SET PROCEDURE INNER(SET BLOBS);
18600
18700 JOBS: EDG (CAM if SIMPLE is to be called)
18800
18900 This routine does a fine scan of a rectangle set around each
19000 of the blobs given to it to try to find more edges. It is similar to
19100 EDGFIN except that GUNNAR and COMPLEX cannot process the output. It
19200 is faster and more efficient than EDGFIN. The output is a set of
19300 blobs processed, of which BLOBS is a subset. It cannot be called more
19400 than once for a given object.
19500
19600 SET PROCEDURE COLGET(SET OBJS);
19700
19800 JOBS: COL
19900
20000 This routine finds the colors of the visible faces of each
20100 object in OBJS which does not already have a color associated with
20200 it. The value of the procedure is the set of all objects for which
20300 new colors were found. The rest already had all their visible faces
20400 colored.
20500
20600 PROCEDURE DISP_OBJ(SET OBJS; BOOLEAN FLAG);
20700
20800 JOBS: none
20900
21000 This routine displays the visible faces of each object in
21100 OBJS. If FLAG is TRUE, the face names and colors, if any, will be
21200 displayed in the center of each face and the object name displayed
21300 just below the object.
21400
21500 PROCEDURE DISP_DEL(SET OBJS);
21600
21700 JOBS: none
21800
21900 All objects in set OBJS have their displays turned off (if it
22000 was generated by DISP_OBJ). No error is indicated if an object was
22100 not being displayed. This routine is called automatically by
22200 REJ_OBJ.
22300
22400 REAL PROCEDURE VERIF(INTEGER X1, Y1, X2, Y2);
22500
22600 JOBS: VER
22700
22800 The verifier is called to determine whether or not an edge,
22900 or line, exists between TV coordinates (X1,Y1) and (X2,Y2). The
23000 value of the procedure is the confidence of the program in the
23100 existance of an edge.
23200
23300 BOOLEAN PROCEDURE CAMCHG(INTEGER COM, LENS; REAL X, Y, Z);
23400
23500 JOBS: CAM
23600
23700 CAMCHG changes the status of the TV camera (camera #1 only).
23800 If 1≤LENS≤2 then the lens will be changed to the 25mm (1) or 50mm (2)
23900 lens if it is not already there. Global integer CAMLENS gives the
24000 current lens number. In addition, COM is decoded as follows:
24100
24200 0 If LENS=1 or LENS=2 change the lens only. If LENS=0 then
24300 update the camera transform. This call is necessary only if a
24400 program changed the TV pan, tilt, focus, or lens without
24500 using this procedure as it will update the transform after
24600 each change.
24700 1 Pan the camera by X radians, where the X axis is 0 and posit-
24800 ive X pans to the left. The current position is in global
24900 real CAMPAN.
25000 2 Tilt the camera by Y radians, where the camera horizontal is
25100 0 and positive Y tilts down. The current position in in glo-
25200 bal real CAMTIL.
25300 3 Both pan and tilt as above, using X and Y.
25400 4 Focus the camera on a plane Z inches from the lens center.
25500 The lens center can be found in row 4 of the camera model
25600 (see below). Global real CAMRANGE contains the current
25700 focus.
25800 Focus and pan. Focus will always be done last.
25900 6 Focus and tilt. "
26000 7 Focus, pan, and tilt. "
26100 10 Center then camera on point (X,Y,Z) in table coordinates.
26200 other The procedure returns the value FALSE.
26300
26400 If the requested action cannot be performed, the procedure
26500 also returns the value FALSE and the global integer CAMFLG can be
26600 decoded to determine the error. The value of the procedure is TRUE
26700 if the action was completed successfully.
26800
26900 The error flag, CAMFLG, is decoded as follows:
27000
27100 0 O.K. if procedure was TRUE; COM had an illegal value if FALSE
27200 1 SERVO routine failed. Hardware problem or bug in library pro-
27300 gram. You may win if you try again. The camera model has
27400 been updated to the point where the motors stopped.
27500 2 LENS is not in the range 1-4. You should not see this error
27600 since CAMCHG should notice it and ignore you. The model will
27700 not be updated.
27800 3 Pan value is out of bounds. The model is not updated.
27900 4 Tilt value is out of bounds. "
28000 5 Focus value is out of bounds. "
28100 6 The lens you asked for is not what you got. Hardware error.
28200 you might win if you tried again. The model has been updated
28300 for the lens specified in CAMLENS. If it is lens 3 or 4 the
28400 model is no good.
28500 7 LOOKUP failed during initialization. This error only occurs
28600 when the camera program is first started. If the YES_CAM flag
28700 does not become TRUE, this may be the reason. DATA[1,SHY]
28800 must be restored.
28900 8 Too many data misses when reading the pots. Hardware problem
29000 which may go away if you try again. The model is updated but
29100 may not be any good.
29200 9 Pots were too noisey when read. Try again and don't let any-
29300 one jump up and down near the camera. The model has been up-
29400 dated but may not be accurate enough to use.
29500 10 AD is not available. A message is sent to the user asking if
29600 he wants to try again. If he responds 'Y', it will be read
29700 again; otherwise this error will be returned. The model will
29800 not be updated.
29900
30000 Whenever the camera program is running, the current camera
30100 model can be found in global real array CAMERA_MODEL as follows:
30200
30300 1:3,1:3 is colineation matrix (TABLE → SCREEN)
30400 4,1:3 is lens center in table coordinates
30500 5,1:2 screen coords of point on image plane pierced by
30600 the axis of the lens
30602 5,3 is always 1
30700 6:8,1:3 inverse colineation matrix (SCREEN→TABLE);
30702 7,1:3 contains the pot readings for PAN, TILT, and FOCUS
30704 8,1 is the camera number
30706 8,2 is the lens number
30708 8,3 is always 0
00100 The following routines are contemplated but not coded yet:
00200
00300 COMPLEX the complex body recognizer
00400 REFIND retrace a blob or object already found
00500 ARM an arm driver
00600
00700
00800
00900
01000 The final solution to the vision problem is now:
01100
01200 OBJ←SIMPL(CURVE(INNER(GETEDGE(0,FALSE))),{EVERY},TO_REJECT);